Skip to content

fix(skills): quote argument-hint as string (Copilot CLI 1.0.65+ compatibility)#9

Open
thejesh23 wants to merge 1 commit into
FavioVazquez:mainfrom
thejesh23:fix/copilot-cli-1.0.65-argument-hint-string
Open

fix(skills): quote argument-hint as string (Copilot CLI 1.0.65+ compatibility)#9
thejesh23 wants to merge 1 commit into
FavioVazquez:mainfrom
thejesh23:fix/copilot-cli-1.0.65-argument-hint-string

Conversation

@thejesh23

@thejesh23 thejesh23 commented Jul 3, 2026

Copy link
Copy Markdown

Summary

Five SKILL.md files declare argument-hint using the flow-sequence form:

argument-hint: ["[path] [--full] [--language <lang>] [--chunk <N>]"]

In YAML, a bare [ opens a flow sequence, so this parses to a one-element array of strings, not a string. That worked as long as skill loaders were permissive.

GitHub Copilot CLI 1.0.65 tightened its skill loader to require argument-hint to be a plain string. Under 1.0.65+ these five sprang skills silently fail to load — the manifest is dropped without a user-visible error.

The fix strips the outer brackets so the value is a plain double-quoted scalar. The semantics inside the string (Copilot / VS Code Agent Skills argument-hint syntax) are unchanged.

-argument-hint: ["[path] [--full] [--language <lang>] [--chunk <N>]"]
+argument-hint: "[path] [--full] [--language <lang>] [--chunk <N>]"

Files changed

File Skill
.windsurf/skills/sprang-analyze/SKILL.md sprang-analyze (Windsurf)
.windsurf/skills/sprang-chat/SKILL.md sprang-chat (Windsurf)
.windsurf/skills/sprang-explain/SKILL.md sprang-explain (Windsurf)
.windsurf/skills/sprang-knowledge/SKILL.md sprang-knowledge (Windsurf)
skills/sprang-analyze/SKILL.md sprang-analyze (top-level / Copilot)

I checked the other six SKILL.md files in each tree (sprang, sprang-why, sprang-team, sprang-onboard, sprang-health, sprang-diff, sprang-domain) — none declare argument-hint, so they are unaffected. .claude-plugin/ and .copilot-plugin/ do not vendor per-skill SKILL.md files in this repo (they carry plugin.json / marketplace manifests only), so no other trees are impacted.

Grep verification after the fix:

$ grep -rEn 'argument-hint\s*:\s*\[' --include=SKILL.md .
(no matches)

Why this shape

Per the VS Code Agent Skills docs and the copilot-cli-for-beginners 05-skills tutorial, the canonical frontmatter shape is:

---
name: my-skill
description: ...
argument-hint: "<free-form hint shown to the user>"
---

argument-hint is a single string. It's not a list of alternatives, and it's not structured — it's the hint text that Copilot renders next to the argument prompt.

Test plan

  • pnpm install --frozen-lockfile && pnpm lint && pnpm typecheck && pnpm test — nothing in this diff touches code paths those exercise, but running them confirms the CI matrix in .github/workflows/ci.yml still passes.
  • Sanity: grep -rEn 'argument-hint\s*:\s*\[' --include=SKILL.md . returns no results.
  • Sanity: for each of the five changed files, head -6 shows argument-hint: "..." (plain scalar, no [).
  • Manual on Copilot CLI 1.0.65+: run copilot in a project with sprang skills installed and confirm sprang-analyze, sprang-chat, sprang-explain, sprang-knowledge now show up in the skill list. (Before this fix, they are silently missing on 1.0.65+.)

I did not run the local pnpm build here (fork-side, no side effects on skill definitions), but the CI job on this PR will exercise pnpm build, pnpm typecheck, pnpm lint, pnpm test, and the Validate plugin manifests step from .github/workflows/ci.yml.

Refs

YAML rule (for reviewers)

A bare [ at the start of a value in YAML opens a flow sequence — see the YAML 1.2 spec §7.4.1. So:

key: ["value"]        # → key is an array: ["value"]
key: "value"          # → key is a string: "value"

Strict consumers reject the array form when the schema expects a string. That's what Copilot CLI 1.0.65 now does.

Five SKILL.md files declare argument-hint using the flow-sequence form
`argument-hint: ["<hint>"]`. YAML parses a bare `[` as the start of a
flow sequence, so the resulting value is a one-element array of strings,
not a string. That worked as long as consumers were permissive, but
GitHub Copilot CLI 1.0.65 tightened its skill loader to require
argument-hint to be a plain string. Under 1.0.65+ these skills silently
fail to load — the CLI drops the manifest without surfacing an error.

Fix: strip the outer brackets so the value is a plain double-quoted
scalar. Semantics inside the string (Copilot / VS Code Agent Skills
argument-hint syntax) are unchanged.

Files fixed:
- .windsurf/skills/sprang-analyze/SKILL.md
- .windsurf/skills/sprang-chat/SKILL.md
- .windsurf/skills/sprang-explain/SKILL.md
- .windsurf/skills/sprang-knowledge/SKILL.md
- skills/sprang-analyze/SKILL.md

The other six SKILL.md files in each tree (sprang, sprang-why,
sprang-team, sprang-onboard, sprang-health, sprang-diff, sprang-domain)
have no argument-hint field and are unaffected. .claude-plugin/ and
.copilot-plugin/ do not vendor per-skill SKILL.md files in this repo,
so no other trees are impacted.

Refs:
- GitHub Copilot CLI 1.0.65 release notes (skill loader tightening)
- VS Code Agent Skills docs — argument-hint must be a string
- copilot-cli-for-beginners/05-skills tutorial — canonical shape
- Egonex-AI/Understand-Anything#540 — diagnostic write-up of the same
  YAML parsing issue (root cause reference; not merged prior art)
- Same latent bug affects Claude Code: anthropics/claude-code#22161
@thejesh23

Copy link
Copy Markdown
Author

Tracking issue: #10 — captures the bug diagnosis and reproducer separately for anyone searching the repo who lands there before this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant